Skip to content

Describe pages, routing and project storage in the technical overview - #1432

Merged
microbit-matt-hillsdon merged 5 commits into
home-pagefrom
tech-overview-projects
Nov 20, 2026
Merged

microbit-matt-hillsdon merged 5 commits into
home-pagefrom
tech-overview-projects

Conversation

@microbit-matt-hillsdon

Copy link
Copy Markdown
Collaborator

docs/home-page.md has been the working notes for the home page and project storage, and is to be removed before home-page reaches main. This moves what should outlast it into docs/tech-overview.md.

Docs only.

What is added

  • Pages and routing: the three pages and their URLs, how the editor chooses a project, #project: links, and iframe controller mode.
  • Projects and storage:
    • the pieces and where they live;
    • opening and saving, including why a flush never reads before it writes;
    • more than one tab;
    • the fallback without IndexedDB and the move of a session storage project at startup;
    • the table of what each kind of import does in each mode.
  • Design decisions, with their reasons where the notes gave one, and a short list of known limits.

The "User interface" section is touched up to mention the pages, and to say Files tab and breadcrumb where it said Project tab and project title.

For review

  • It assumes the open PRs against home-page have merged, in particular Drop a #project: link that cannot be read #1431: the description of #project: links (the home page sending a pending link on to the editor, an unreadable link being dropped) is that PR's behaviour.
  • It is written for the document's existing audience, people working on the editor or reusing parts of it, so process notes, open decisions and outstanding launch tasks from home-page.md are left out. They need a home elsewhere before that file is deleted.
  • home-page.md is not changed or removed here. One code comment, in src/pages/DefaultPageLayout.tsx, still points to it for the dense preset discussion and will need attention when it goes.
  • Reasons are only given where the notes recorded one. Where they recorded a decision without a reason, such as no project id in the URL, the overview states the decision and stops.

docs/home-page.md has been the working notes for the home page and project
storage and will be removed before this reaches main. This moves what
should outlast it into the technical overview: how the pages and routing
fit together, how projects are stored and saved, what happens across tabs
and without IndexedDB, what each kind of import does, and the decisions
that are not obvious from the code.

It describes the code with the open pull requests against home-page
merged, in particular #1431 for #project: links.
@github-actions

Copy link
Copy Markdown

Preview build will be at
https://review-python.microbit.org/tech-overview-projects/

@microbit-matt-hillsdon

Copy link
Copy Markdown
Collaborator Author

A step towards being able to delete home-page.md.

Comment thread docs/tech-overview.md Resolved

@microbit-robert microbit-robert left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. One minor comment / suggestion, but will approve.

Co-authored-by: Robert Knight <95928279+microbit-robert@users.noreply.github.com>
@microbit-matt-hillsdon
microbit-matt-hillsdon merged commit df06f4a into home-page Nov 20, 2026
3 checks passed
@microbit-matt-hillsdon
microbit-matt-hillsdon deleted the tech-overview-projects branch November 20, 2026 17:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants